Documentation Mailing Lists FAQ Frequently Asked Questions v2

Browse: Technical Questions

We have slice data and structure exported to AA.XML file and we want to import it back to the AA. The problem is, that the AA.XML file is 24 MB.

The solution:

The problem could be in PHP setting. Here's what I had to change in php.ini file to get it going:

1. post_max_size: increased from 8M to 32M
2. upload_max_filesize: increased from 2M to 32M

Those first two were key -- from the php log the upload was clearly exceeding both of these parameters. Obviously, if the upload was bigger than 32M (ours was about 24M) this might need to go even bigger.

I also increased these others. I think the upload wouldn't have completed in the default times, but I'm not sure which parts of the operation count towards which of these:

1. max_execution_time: changed from 30 to 120 seconds
2. max_input_time: changed from 30 to 120 seconds
3. memory_limit: changed to 32M

The output generated by AA is controlled by aliases. The aliases are 10 letters long words defined on 'Admin' -> 'Fields' -> 'Edit' page. Aliases are obviously expanded to the content of some database field or its modification (like How to use aliases alias). For modification of behavior of the alias we use alias functions, as described on
http://apc-aa.sourceforge.net/faq/#216.
http://apc-aa.sourceforge.net/faq/#291.

Since the AA version 2.1 there is possibility to use the aliases NESTED, which means that you can use another alias in the alias definition. For example this Parameters to f_c alias functions are possible:

!:<img src=":" _#PHOTO_WI _#PHOTO_HE alt="photo">::

which displays image (if it is defined). The aliases _#PHOTO_WI _#PHOTO_HE must be defined, of course.

You can use there not only the aliases, but it is possible to use any of database field directly there. Imagine, we store type of record in switch.........1 field (for example text/audio/video). If we create three images - icon_text.gif, icon_audio.gif, icon_video.gif, we can add an icon before each link by the following Parameters to f_m alias function:

<img src="img/icon_{switch.........1}.gif" width="14"> :text...........1::href:class="green10"

The AA version 2.2-pre (04/25/2002) give you new possibilities in alias definition - IN-LINE ALIAS DEFINITION. The parsing of format strings was rewritten, so now you can define aliases not only on 'Admin' -> 'Fields' -> 'Edit' page, but you can define it directly inside the format string (= 'Fulltext HTML code' on 'Design' -> 'Fulltext' page, for example). The new features are 100% backward compatible.

The alias definitions are surrounded by curly braces. There are the possibilities:

1. direct display of some field
   
   ... there is displayed headline: {headline........} <br> Source: ...
   
   
2. constant display
   
   Constants are stored in database as values, but it is possible to convert value back to name, description, ...
   The syntax is : {const_name:category.......1}, {const_description:category.......1}, which displays name (description) of constant stored in field category.......1.
   You can grab following information for the constants:
   

   const_short_id	short_id
   const_name	name
   const_value	value (the same as {category.......1} )
   const_pri	priority number
   const_group	name of constant group
   const_class	class (APC parent category)
   const_id	long constant id
   const_description	description (defined on hierarchy editor pages)

   
   
   
3. display of multivalue fields
   
   ... fields in AA could contain multiple values (categories, ...). It is possible to diesplay it: The example is directly in Item Manager of 'Test News' slice. The syntax is:

   {@category.......1}	displays list of 'values' - comma separated (comma is default)
   {@category.......1:-}	displays list of 'values' - dash separated (it is usefull for example in display of related items: {view.php3?vid=11&cmd[11]=x-11-{@relation.......1:-}}
   {@category.......1:,:<b>_#1</b>}	displays list of 'values' in bold - comma separated (_#1 is alias for the values)
   {@category.......1:,:<a href="/category.shtm?conds[0][category.......1]=_#1">_#1</a>}	displays list of categories with link to the each category
   {@category.......1(const_name,const_value,const_short_id):,:<a href="/category.shtm?conds[0][category.......1]=_#2">_#3 _#1</a>}	displays list of categories with link to the each category, but the text shows category name (and short_id) instead of value. You can use as many constant translations as you want in the parethes. See 'constant display' for list of possible values in previous paragraph.

   
   
   
4. direct display of a variable defined with als or in $apc_state:
   
   ...view.php3?vid=123&als[heading]=My Page

and then ... <h1>{heading}</h1>
   
   The same syntax will find variables defined in apc_state (by the site module).
   
   
5. modification through alias functions:
   

   ... The previous example is good, but sometimes we need to modify the database field before it is displayed. For example the date field is displayed as number if seconds since begin of year 1970, which is probably not exactly what we want to show to user. The solution is to use alias function modification, which has the following syntax:
   
   alias:<the field>:<alias function>:<parameters>
   
   So, in text (format string) could be the publish date displayed by {alias:publish_date....:f_d:j.n.Y}. There you can use any alias function with any parameters.

   The parameters could be nested, so inside curly braces you can use any alias (How to use aliases), any other field ({headline........}) or any other in-line alias definition. There is no limit in level of nesting.

   For example, conditional display of date could look:
   
   {alias:switch.........1:f_c:text:{alias:publish_date....:f_d:j.n.Y}<!--:-->::}
   
   or if we have 06/19/2002 alias defined:
   
   {alias:switch.........1:f_c:text:06/19/2002<!--:-->::}
   

   Both this constructs displays date only if switch.........1 is equal to 'text'. ...

6. comments
   

   ... as addition to in-line aliases you can {# make comments} which is not displayed in result html code. It could be nested again, so you can {# comment out _#ALIASES_ as well as fields {headline........} or alias definitions } - nothing will be in result HTML code ...

7. switch
   

   ... the really new and very useful construct is switch. Many of us knows the troubles with conditional expressions, managed so far by f_c function. Now there is much better solution, which allows more options, regular expressions, ... The syntax is:
   
   {switch(<condition>)<option1>:<output1>:<option2>:<output2>:...[:<default_output>]}
   
   which we can explain on example:
   
   {switch({number.........1})1:one:2:two:[3-7]:more:too much}.
   

   This construct evaluates the condition, which is the content of the number.........1 field in our case. If content of the field is equal to 1, the 'one' is printed. Because 'options' are regular expression, we can specify the third option as [3-7] which means any number in range between 2 and 7. The default option is 'too much' in our case. The evaluation of options goes from left to right and the output is printed only for the first matching option.

   The 'switch' could be used instead of f_c alias function in many cases:
   
   {switch({switch.........1})text:06/19/2002}
   
   This expression could replace the expression in the paragraph 2)
   

   Another example displays text 'Continuos grant', if the field unspecified....2 is filled by 'yes', 'on', 'true' or '1'. Else it displays expiry date:
   
   {switch({unspecified....2})yes|on|true|1:Continuos grant::12/11/2007}
   

   Display of phone number, if specified (as obvious, '#:' stands for ':' if you do not want to use it as argument separator:
   
   {switch({con_phone......1}).+:Tel#:{con_phone......1}}
   

   Last example demonstrates the fact, that there is no limit in <condition>. There could be not only field (in curly braces), but there could be also any alias, alias definition or its combination. The level of nesting of 'curly braces expressions' is again unlimited.
   
   {switch({1})[1-9][0-9]*:There is discussion under this item}
   

8. Inclusion of a view
   {view.php3?vid=123}

   Returns content of view 123. View uses the just like the view.php3 script, and can nest other {} structures. (e.g. {view.php3?vid=122&cmd[122]=c-1-{f}} ) Very useful for displaying related items e.g. {view.php3?vid=33&cmd[33]=x-33-{relation.......1}}

9. includes (added 06/20/2002 - will be in AA v2.2.1)
   

   ... Sometimes we need to include some file or output of some script into the page. Now, there is {include(<file>)}, which will be replaced by the file. The file is called through HTTP request. No matter if included file is html, shtml, php, ...:
   
   the page was visited {include(cgi/counter.pl?id=222)}
   
   (the result of http://www.example.com/cgi/counter.pl?id=222 will be printed)
   
   APC news: {include(http://apc.org/apps/aa/view.php3?vid=112)}
   
   (the remote view (from APC site) will be printed)
   
   If you want to include other slices, it could be usefull to pass the URL parameters to the included file. In this case use the special URL_PARAMETERS constant:
   
   {include(fulltext.shtml?URL_PARAMETERS)}
   
   The limits:

   • It runs only on http:// sites (https:// is not supported until PHP v4.3.0 will be released)
   • There is also limited size of included file. The default limit is 400kB, but you can change it by INCLUDE_FILE_MAX_SIZE constant in config.php3.
   • Also you should know, that each include generates one more HTTP request to server. That's why also the performance is not as big as for the other alias types.
   This can be used in an alternative syntax {include:<file>} or {include:<file>:http} which work exactly the same or {include:<file>:fileman} which will try and read the file directly from the Fileman directory for the slice being used. (this code is new 23 may 2003 and the definition of which slice is being used might change)

10. mathematics operations (new in AA v2.4.0)
    

    ... If you want to compute some walue from datadase field, use the {math..} alias. The syntax is ...:
    
    {math(result_formatting) description1: expression 1: description2: expression2:...:description x : expression x }
    
    where:
    

    result_formatting	has 3 parameters separated by '#' (number of decimals # decimals separator # thousands separator)
    description	can be any text or html and is displayed before result of expression ("#:" mean ":")
    expression	in expression can be used numbers (decimal separator is ".". Aliases can be used of course) and characters: + - / * ^ . ( )

    
    example 1 - use in inquiry
    

    
    <img src="red.gif"   height=10 width="{math(0#,#) : {_#ANSVER1_} / ({_#ANSVER1_} + {_#ANSVER2_} + {_#ANSVER3_})* 100}%">  _#ANSVER1_ <br>
    <img src="blue.gif"  height=10 width="{math(0#,#) : {_#ANSVER2_} / ({_#ANSVER1_} + {_#ANSVER2_} + {_#ANSVER3_})* 100}%">  _#ANSVER2_ <br>
    <img src="green.gif" height=10 width="{math(0#,#) : {_#ANSVER3_} / ({_#ANSVER1_} + {_#ANSVER2_} + {_#ANSVER3_})* 100}%">  _#ANSVER3_ <br>
    
    
    if _#ANSVER1 = 25, _#ANSVER2 = 50, _#ANSVER3 = 250 result will be:
    
    
    <img src="red.gif" height=10 width="8%">  25   <br>
    <img src="blue.gif" height=10 width="15%">  50   <br>
    <img src="green.gif" height=10 width="77%">  250   <br>
    
    

    
    example 2 - cost of ordered services last year
    

    
    {math(2#,# ) <br>mails=:{_#NOOFEMAI}*{_#EMAPRICE}:
                 <br>web=:{_#WWWPRICE}:
                 <br>technical support=:{_#NOOFHOUR}*{_#HOURPRIC}:
    <br><hr>total={_#NOOFEMAI}*{_#EMAPRICE}+{_#WWWPRICE}+{_#NOOFHOUR}*{_#HOURPRIC}
    }
    
    
    result:
    
    mails=450,00
    web=1500,00
    technical support=2400,00
    ----------------------------
    total=4350,00
    

11. user informations (new in AA v2.6 (CVS 05/19/2003))
    

    In AA v2.6 is new Reader Management, where you can control access to directory or file through AA admin interface (see Reader Management). You can then display informations about logged user by {user:} construct.
    The syntax is following:
    

    {user:}	displays login of current user (this option do not search in database, so it is quick) You can use this parameter even if you do not use Reader Management slice and you are using standard Apache's password file auth ...
    {user:password}	displays password of current user (in plain text) (this option also do not looks into database, but into internal server variable, so it is also quick)
    {user:headline........}	displays headline........ field for current user, which is grabbed from Reader Management slice. There is no need to specify in which Reader Management slice user is, because all users are unique in all Reader Management slices. If the Reader Management slice is protected by password (see 'Slice Admin' -> 'Slice' -> 'Password for Reading'), you have to add slice_pwd parameter to view.php3 (or slice.php3), in which you want to display user's database info. You can of course display any field from Reader Management slice.
    {user:role}	displays user's permission role (author/editor/administrator/super/undefined) (usefull in AA admin interface when you want to display another informations to authors and editors - use it in switch() - like {switch({user:role})editor:_#POSTED_BY} )

    Such construct you can use in any view or slice - just like any other aliases.

12. page scroller (for site module only)
    

    ... If you want to use page scroller (Page 1 | 2 | 3 | ... ) in view , which is part of 'site'! (see site module), the {scroller} syntax construct is the right tool. You just add {scorller} to the view, there you want to usepage scroller - probably in the 'Bottom HTML' fileld of the view:
    
    {scroller:Page ::class="blue"}
    
    The syntax for {scroller} is:
    
    
    {scroller:begin:end:add:nopage}
    
    where:
    

    begin	text to be shown before page numbers
    end	text to be shown after page numbers
    add	option to be added to page number <a href=".." class="blue10v">1</a>
    nopage	text to be shown wnen there are (yet) no pages (so the scroller is not displayed)

    Then you use quite normal view include using {p} state variable, which stores the page number in the site module's spot:
    
    {view.php3?vid=32&set[]=page-{p},listlen-10}

13. Debugging

    Because it is sometimes unclear which substitutions are available at a certain point, {debug} will output some hopefully useful information

If you get the error: "No slice found for you" after logging into AA after doing a CVS update, then you may have forgotten to fill in the AA_ID in the config.php3 file

If you were a loser (like I have been) and did back-up your AA_ID, it can be retrieved from the AA database...

Using phpMyAdmin or your excellent MySQL skills:
Look for entries in "perms" table that have aa in "object_type" column, "objectid" is your installation ID.

There are several places where APC-AA sends mail, and it can be confusing, especially since it is really easy to configure them wrongly so they don't work, and little help for figuring out why. Lets consider 4 cases. The Bugs and Weaknesses of each method are shown because they may help pick which method to use, and also help guide as to places for further development.

Slice Admin or Editor wants notification of new items added to Hold bin, or edited or whatever.

Use the Email Notification functionality, here you can specify different messages to be sent when messages are added / edited to Active / Hold bins, and different recipient lists, so for example you can create a message to an Editor whenever a new message arrives in a Hold bin, and maybe a different message to the sysadmin when an item is moved into the Active bin (usually by the Editor). The message could be just something like "An item has been posted in Xyz slice" or by using aliases can include any fields of the item posted.

Bug/Weakness: You can't use aliases in Subject line, this might be fixed in some version (but is unlikely to be a priority!)
Limitation: The members of the list can only be changed by a slice admin, so don't use this for Alerts ...

A number of people want to receive items posted to a slice

Use a reader management slice (see doc/reader.html) in conjunction with Alerts (doc/alerts.html).

Bug/Weakness: its complex to setup, and frequently people don't succeed, if you don't follow the Tutorial Step by Step (in doc/alerts.html) you probably won't get it to work.

Bug/Weakness: In particular it requires creating an anonymous form, which depends very much on the way its being used (e.g. called from something.shtml or site.php3). One possible development fix would be creating a PHP3 script that took the slice-id of an Alerts module as a parameter and did this much more simply.

Bug/Weakness: documentation says 5.3a: View with type "Alerts Digest", when it means "Alerts Selection Set".

A number of people want to be in an email discussion, i.e. all posting to each other.

Use a Reader Management Slice (see doc/reader.html) in conjunction with Mailman, APC-AA is used to manage the mailman list

Bug/Weakness: you can no longer manage the lists (subscribe/unsubscribe) by email to the Mailman account once you've done this, mailman will almost certainly be sending out email telling the users they can!

Bug/Weakness: You have to understand both apc-aa AND mailman to get this to work since doc/reader.html refers to tasks that require knowing where to find and how to configure mailman.

Bug/Weakness: There is no link between information in a slice, or discussions, and the email discussion, i.e. this is not - like yahoo groups - a web OR mail interface to the same set of data.

Reports of failure (Jason Diceman) partly due to server setup

People wish to receive copies of new comments in Discussions by Email

See "FAQ/Discussions as Mail List", this allows a field in each item to specify a mailing list.

Bug/Weakness: This field has to be added to every item, it can't be specified at the slice level (make the field Required but not Shown and set a default). This is particularly difficult if you want to retrofit discussions to an existing slice, or something coming in over RSS.

Bug/Weakness: This can only go to a single email address, so you have to manage the list somewhere else outside APC-AA (there is no way to for example link it to Alerts).

Bug/Weakness: It doesn't appear to work, sends blank emails.

Summary

Note:

There is no integration for receiving email, although there has been discussion (where?) about posting articles by mail

• nothing - standard "no item found" message is displayed (this setting is historical)
• any text - the text is displayed. From AA v2.6 you can also use aliases and other AA expressions like {switch()...}...
• <--Vacuum--> - if you use this keyword (exactly!), nothing is displayed.

One recomendation is to write something that relates to the slice content, e.g. "No news found" or "No events found", with in visible HTML or a comment tag. This helps with both usability and view development problem solving.

The hit is counted in this cases:

1) with slice.php3
   - if you will display an item with x=24425 url parameter
   - if you will display an item with sh_itm=42567a8736342562782abe782c
   - if you will use banner url parameter (banner=2-38)

2) with view.php3
   - if you display an item with cmd[22]=x-22-24425
     Note 1: if you use more than one item with x command
             (like cmd[23]=x-22-24425-24461-23612) only first
             item is counted)
     Note 2: if you want to display an item and do not want to count
             hit for such item, use 'o' command
             (like cmd[23]=o-22-24425), which works exactly in the same
             way as 'x', but it do not count hits.
   - if you use random parameter (ie. set[23]=random-1)

For speedup of database operations we use log table for hits count, from
which it is time to time copied to item table. You can configure this
behavior in include/constants.php3:

// CountHit probability - how offen write logged hits to item table
define ("COUNTHIT_PROBABILITY", 50);

This means that after 50 hits (approximately) (in whole AA) the hits are
written to item table (= displayed to users).

For more info see CountHit() function in include/util.php3

No, it is not possible - at least yet.

 There is a problem with characters encoding and different languages. Each language uses its own character encoding (like iso-8859-1 for English and Spanish, iso-8859-2 or windows-1250 for Czech, ...). If you select language for the slice, you also select (implicitly) the character encoding. If we allow users to use different language in the same slice, each item will be in different encoding, ... which means problems.

<!--#include virtual="/aaa/fillform.php3?show_result=http://ecn.cz/show_result.php3&form=..."-->

err_page[validate][username......]="err_username.shtml"
err_page[validate][*]="err_validate.shtml"
err_page[*]="err_unrecognized.shtml"

<!--#include file="err_top.shtml"-->
The username you entered has already been used. Please try another username.
<!--#include file="err_bottom.shtml"-->

If you want to display some view on page, which is stored on site where is not installed AAs, you have three possibilities.

1. use remote, remotec or remotec.php
2. create javascript view - this is good if you want to do something complex with the Javascript.
3. use the jsview.php3 to display existing view.
   

This answer covers point 3) - jsview.php3

The usage is easy. Just replace SSI include in original shtml age with the javascript one. The jsview.php3 takes exactly the same parameters as view.php3.

For example, if the old SSI code in page.shtml was:

<!--#include virtual="/apps/aa/view.php3?&vid=2&cmd[2]=c-1-APC" -->

the new javascript code in page.shtml would be:

<script type="text/javascript" src="http://www.apc.org/apps/aa/jsview.php3?vid=2&cmd[2]=c-1-APC"></script>

Normally you will want either a Item listing, Full text or Static Page view.

• Item Listing - these are used like the main Index view to generate a list of some or all the items in a slice.
• Fulltext View - these are used to display a single item.
• Item Digest - not sure what these are.
• Discussion - used for creating discussions
• View of Constants - used to display list of constants (ie. categories).
• RSS Exchange - used to exchange items with Content Management Systems that use this standard
• Static Page - these are a bit like macros, they are not related to a specific item or slice, but can be used where the same content, or parameterised content is needed on many pages.
• Javascript item exchange - used to view items on a site without AA installed.
• URL Listing - special view used mainly for creating list of links to all articles in the slice, which is used for search robots and fulltext indexers like Google, HtDig or MnoGoSearch. It is very similar to Item Listing, but you can use just very limited set of fields and aliases, so there is no problem with "memory limit".
• Calendar view is a complex view used for showing event items within a monthly calendar.

• Link listing and Category listing views are used for Links module - you can customize the design of links listing and category listing just like jot normal AA items. The usage is analogous to Item listing and is quite simple, but deep documentation of those views wait for someone, who will have resources to document Links module.

Requirements for ActionApps Unix Hosting

• Strongly prefer Apache
• Ability to create crontab (but this only needs to be done once, so could be done by the hoster).
• PHP version 4.3+, safe mode turned off, with mail function enabled
• At least one MySQL 3.2x database
• SSIs local to virutal server account
• Shell access (mostly for updating from CVS)

Optional:

• HTACCESS (used for Reader Management permissions)
• Mailman mailing lists with list creation/deletion control (not necessary, but AA Reader Management has some options for admining Mailman list subscriptions.
• SSIs to other virtual server accounts (if you want to share an APC-AA install between different virtual server accounts)
• MysqlAuth (Apache Module) if you want to use Reader Management persmissions

Please add your comments below about AA installs that have and have not worked for you...

This FAQ interface was developed by Jason at Commons.ca

APC ActionApps is a free software content management system initiated by the Association for Progressive Communications (APC) APC - Internet and ICTs for social justice and development